           A MANUAL FOR RADIO SHACK'S EDITOR/ASSEMBLER

                       ----- Part One -----


                       Dennis Bathory Kitsz


        The Editor/Assembler for the TRS-80 Model I, as sold by Radio Shack or as modified by Apparat, Byte Miser, The Alternate Source and others, can be a powerful tool for programming in machine language.  Unfortunately, using the Editor/Assembler can be as much a mystery as machine language itself.  This is the first of a series of articles which will form a supplementary manual detailing the operation of the Editor/Assembler, with examples and explanations.  Ownership of the Editor/Assembler, its documentation, and the Z80 Technical Manual is assumed.


Introduction
------------

        An assembler is a programmer's intermediary tool, used between an English-language concept and a final product in order to create the binary code which addresses the controlling microprocessor inside a computer.  The final code is in binary form (which in some form is the final product of any programming language), called "object code".  That code is a continuous block or stream of on and off pulses which, when resident in a computer's memory, causes it to perform a series of tasks determined by the programmer.

        Machine code is different from high-level interpreted languages like BASIC in significant areas.  It is faster, because it speaks to the processor directly.  It contains no inherent prompting, error-checking, display routines, input/output capabilities, or other qualities with which users of BASIC are familiar.  It is thoroughly elementary.  Machine code is that body of building blocks from which higher languages are built, including the assembler itself.

        An assembler simplifies the production of this machine language in several ways:  it resolves labeled cross-references (identifying program areas by name rather than by number); it determines program branching (change of program flow); it accepts instruction names (mnemonics) in place of binary code; and it interprets the three major number systems (decimal, hexadecimal, and octal) used in machine language programming.  All this is achieved by use of an intermediate language between English and machine code, called "source code".

        Source code consists of four elements.  The first is a line number, used for the programmer's reference.  Unlike BASIC, the only purpose of any line number is to keep the source code in order, insert and delete information.  It is not used by the assembler in the final generation of object code.

        The next source code element is the label, one of the premier features of any assembler.  Where part of a program must be referenced elsewhere (such as a jump, subroutine, table, entry point, end point, memory reference, etc.), a label is used.  For example, if a reference is to be made to the video display in a source program for use in producing object code, its memory location may be identified numerically, and that numerical location labeled "VIDEO".  Any reference to VIDEO in the assembler source code will be resolved to the memory location the programmer has labeled VIDEO.  In BASIC, such a feature would be akin to being able to label GOTO's and GOSUB's, like GOTO GETCHAR or GOSUB SORT.

        The third source code element consists of the microprocessor's instruction set -- its operation codes, the "opcodes".  This instruction set is defined by the microprocessor's manufacturer (in this case, Zilog, creators of the Z80), and is made up of wordlike abbreviations for binary machine language information.  An example:  the binary pattern 00111100 can be written 3C hexadecimal, or 60 decimal.  Its mnemonic -- the verbal abbreviation which describes its computer function -- is INC A (increment by one the contents of the accumulator register).  The last method is the way instructions are written into the assembler.  Opcode details will be discussed in depth later.

        Finally, the assembler source code permits the insertion of comments (the equivalent of BASIC REM statements) which have no effect on the final object code, serving only as the programmer's documentation.

        Part of the Radio Shack Editor/Assembler's power comes from its ability to manipulate the source code and text easily, with error messages and a high level of crashproofing.  Lines may be inserted, deleted, and edited with the same fluidity as those in BASIC, plus a fast line-renumbering feature is provided.  Listings may be appended from tape.  Furthermore, the entire source listing may be string-searched in the manner of a text editor.  The code listing may be printed; saved on tape (or disc with the Apparat disc modification); printed without line numbers in the text mode; assembled in order to produce a screen or printed listing, a symbol table (table of labels and the references), merely to check for errors, or in order to create an object code.

        In sum, the Editor/Assembler is an important programming tool for anyone who needs machine language programs, whether free-standing or as extensions to the computer's built-in BASIC interpreter.  As a bonus, it is provided with text editing features.


Loading and Initializing the Editor/Assembler
---------------------------------------------

        As sold by Radio Shack, the Editor/Assembler will function equally well with Level I or Level II machines.  A disc version is available from Apparat with NEWDOS, and a Model III modification package has been prepared by Byte Miser Software.  Editor/Assembler text modes can be enhanced with Quill Driver from The Alternate Source.  All versions require at least 16K read/write memory (RAM).

        To load the tape versions of the Editor/Assembler, refer to page 2 of the Editor/Assembler User Instruction Manual.  The disc version is loaded by entering EDTASM from DOS command level, or CMD"EDTASM" from BASIC.  Where overlays are used (such as the Model III modification package or various optional keyboard drivers), the program is loaded from tape, but not executed using the slash ("/") entry point.  Follow the instructions provided with commercial overlay programs.

        Now that the Editor/Assembler has been loaded under the name EDTASM, further references to it will be by the name "Edtasm".  When the program is executed, a message similar to that shown below will be displayed:

                TRS-80 EDITOR/ASSEMBLER 1.1
                *_                         

The asterisk (*) is Edtasm's prompt, like the greater than (>) sign is BASIC's prompt.  It is asking for one of Edtasm's 16 commands.  Also like BASIC, the cursor is a steady underscore character, and it will follow characters which you type.  The keyboard works normally, with a few exceptions -- there are no shifted alphabetic characters, plus a unique tab function is provided which will be detailed later.  _Note_:  any function will be aborted and the Edtasm prompt returned when the <BREAK> key is pressed.

        The area of memory in which source code is entered is called the source or text buffer.  Lines may not be typed into the buffer directly from command mode, but must use line numbers.  Edtasm provides an automatic line-numbering feature which is required for all editing, insertions, deletions, or replacements.  In the simplest mode, and upon entering Edtasm, you can begin inserting lines by typing:

                I               <ENTER>

Line 00100 will be printed on the screen, and will be advanced in increments of 10 whenever <ENTER> is pressed.  This is the default value for the line-insert (I) command.  Had the command --

                I 150,5         <ENTER>

-- been typed instead, line 00150 would have been printed on the screen with the subsequent line numbers being advanced in increments of 5.

        If you used "I" alone in the first example, you will have line 00100 displayed on the screen.  Press <ENTER> several times, then touch <BREAK>.  Your screen should look something like this:

------------------------------------------------------------
Screen 1.                                                   
------------------------------------------------------------
                TRS-80 EDITOR/ASSEMBLER 1.1
                                           
                *I                         
                00100                      
                00110                      
                00120                      
                00130                      
                00140                      
                *_                         
------------------------------------------------------------

When you have a full source listing in place, you will want to refer to certain lines, just as in any BASIC listing.  You are able to print any single line or group of lines on the screen by using the P command.  There are only a few peculiar Edtasm conventions; one of them is the use of the colon (:) instead of a dash to indicate "to" in listings.  Printing lines 100 to 200 would be P100:200 instead of P100-200.  Other more useful conventions are the pound (#) to designate the first line of the source code, the star (*) for the last line, and the period (.) for the current line.  The up and down arrows perform simple scrolling functions.  Only the period (.) is used in BASIC, so you can see how these other Edtasm conventions are particularly useful.

------------------------------------------------------------
Table 1.                                                    
------------------------------------------------------------
        P               Prints 15 lines, beginning at the
                                current line.
        P.              Prints the current line only.
        P100            Prints line 100.
        P100:200        Prints lines 100 through 200.
        P#              Prints the first line in the buffer.
        P*              Prints the last line in the buffer.
        P#:200          Prints the first line up to and
                                including line 200.
        P.:200          Prints the current line up to and
                                including line 200.
        P200:*          Prints line 200 through to the
                                last line.
        P.:*            Prints the current line through
                                to the last line.
        P#:*            Prints from the first line through
                                to the last line (the 
                                complete source text).
        Up arrow        Prints the line previous to the
                                current line.
        Down arrow      Prints the line following the
                                current line.
------------------------------------------------------------


Using <SHIFT@> will stop the scrolling action during P commands in the same manner as it does in BASIC.  It will also pause during printing, assembly, or any other function except tape loading and saving.

Reminder:  Touching the <BREAK> key will return control to Edtasm command mode (the * prompt).  Also note:  Remember _not_ to use the word LIST; Edtasm will think you want to load a source program with the name IST!

        The from/to conventions using the colon, pound, period and star hold for the delete (D) command, such as:

------------------------------------------------------------
Table 2.                                                    
------------------------------------------------------------
        D. (or D)       Deletes the current line.
        D100            Deletes line 100.
        D100:200        Deletes lines 100 up to and
                                including line 200.
        D#              Deletes the first line.
        D*              Deletes the last line.
        D#:100          Deletes all text up to and 
                                including line 100.
        D200:*          Deletes all text from line 200
                                to the end.
        D.:*            Deletes all text from the current
                                line to the end.
        D#:*            Deletes the entire buffer contents.
------------------------------------------------------------


Like the Print (P) and Delete (D) commands, the from/to conventions of pound (#), asterisk (*), period (.), and colon (:) hold for the Hardcopy (H) and Text (T) commands, both of which involve a printer connected to the computer.  Edtasm's Hardcopy is identical to its Print, except that the complete listing is sent to the printer instead of the screen.  Print (P) works like BASIC's LIST, whereas Hardcopy (H) works line BASIC's LLIST.  Note that (also like Level II BASIC) the execution of a Hardcopy or Text command will hang the computer if no printer is present.  The Reset button, because it is linked to BASIC or disc boot functions embedded in ROM, will not return to Edtasm, but rather will destroy Edtasm and the entire text buffer.

        The Text (T) command also sends the listing to the printer, but the line numbers are omitted.  This makes the Text mode ideal for simple preparation of textual material such as letters -- editing and renumbering functions are available that provide a simple text editor as a bonus to the assembler functions of Edtasm.  There is no comparable poor person's text editor in BASIC's command repertoire.

        Here are some examples of commands using Hardcopy (H) and Text (T):

------------------------------------------------------------
Table 3.                                                    
------------------------------------------------------------
        H               Sends 15 complete lines of the
                                listing to the printer.
        H.              Sends the complete current line
                                to the printer.
        H100            Sends the complete line 100 to the
                                printer.
        H#:*            Sends the complete listing to the
                                printer, with all line
                                numbers in place.
        T               Sends 15 lines to the printer with
                                the line numbers omitted.
        T.              Sends the current line to be printed
                                with line number omitted.
        T200            Sends the text of line 200 to the
                                printer
        T#:*            Sends the complete text to the
                                printer without line numbers.
------------------------------------------------------------


        The final simple Edtasm command is Return to BASIC (B).  This command will present the Memory Size prompt in Level II, or reboot a disc system.  The B command is essentially fatal; unless you have an Edtasm modification in place (such as that written by Byte Miser Software), you cannot jump to BASIC or return to Edtasm without losing the text buffer and important Edtasm pointers.


A Sample First Session
----------------------

        Load Edtasm and initialize it with a Line Insert (I) command.  Line 00100 will appear.  Now type the lines below.  The first line number is already in place as a result of entering the I command, and subsequent lines will be presented automatically.  The bracketed command <TAB> means press the right arrow.  If you make any errors, you may backspace as usual to correct them.  Backspacing over a <TAB> will result in the cursor moving back the _entire_ tab position.  SHIFT-left arrow will erase the entire line, as in Level II BASIC.  Reminder:  The SHIFT key does not function with alphabetic characters.

------------------------------------------------------------
Entry 1.                                                    
------------------------------------------------------------
    00100<TAB>ORG<TAB>5000H<TAB><TAB>;DEC 20480<ENTER>
    00110ENTRY<TAB>LD<TAB>HL,3C00H<TAB>;VIDEO<ENTER>
    00120<TAB>LD<TAB>DE,3C01H<TAB>;VIDEO+1<ENTER>
    00130<TAB>LD<TAB>BC,03FFH<TAB>;TOTAL SCRN<ENTER>
    00140<TAB>LD<TAB>(HL),255<TAB>;BLOCK CHAR<ENTER>
    00150<TAB>LDIR<TAB><TAB><TAB>;BLOCK MOVE<ENTER>
    00160<TAB>RET<TAB><TAB><TAB>;TO BASIC<ENTER>
    00170<TAB>END<ENTER>
------------------------------------------------------------

When you have completed the entries above, the screen should look like this:

------------------------------------------------------------
Screen 2.                                                   
------------------------------------------------------------
    00100         ORG     5000H           ;DEC 20480 
    00110 ENTRY   LD      HL,3C00H        ;VIDEO     
    00120         LD      DE,3C01H        ;VIDEO+1   
    00130         LD      BC,03FFH        ;TOTAL SCRN
    00140         LD      (HL),255        ;BLOCK CHAR
    00150         LDIR                    ;BLOCK MOVE
    00160         RET                     ;TO BASIC  
    00170         END                                     
------------------------------------------------------------

There is a lot to observe in this short sample.  First of all, ordinary spaces might have been used in place of tabs (the right arrow).  However, using spaces consumes more memory than necessary in the source code buffer, and you will certainly overrun your available memory if you make a practice of using spaces instead of tabs.

        Notice the ORG statement in line 100.  Assembly language source programs must have an ORG (origin) command; this tells Edtasm where the final object program will reside in memory so it may make all the necessary calculations for program jumps, table addresses, etc.  Since the default ORG is 0000, and 0000 is in ROM, creating programs at this address will have no function in the TRS-80.

        In the sample program above, 5000 hexadecimal (20480 decimal) has been used, which is the just at the end of 4K read/write memory.  Also, take note of the convention used to mark hexadecimal numbers:  5000 hexadecimal is written 5000H.  Decimal is the default numbering system; that is, Edtasm assumes any unspecified number is a decimal number, such as in line 140.  Decimal 255 is printed there, but this might also have been written 255D (which is preferable).  It is good practice _always_ to indicate the number system being used, even with Edtasm's decimal default.  That is because after you have been programming in assembly language for some time, certain numbers become familiar, and indicating the number system with H (hex) or D (decimal) avoids leaving the familiar numbers accidentally "unhexed".

        If on the other hand you have been doing assembly programming using the 8080 microprocessor, there is a good chance that you learned your machine-code programming in octal.  Edtasm offers octal numbering too.  Here are all three ways lines 140 might have been written:

------------------------------------------------------------
Example 1.                                                  
------------------------------------------------------------
        00140           LD      (HL),255D
        00140           LD      (HL),0FFH
        00140           LD      (HL),377O
------------------------------------------------------------

The last example is "three-seventy-seven-oh", that is, 377 octal.  It is unlikely that most TRS-80 users will be conversant in the octal numbering system, but since the Z80 microprocessor's internal architecture is in fact octal, making the option available was an important design feature of Edtasm.


                     Part Two 

                Dennis Bathory Kitsz                    



Another important feature shown in the sample listing is the label in line 110, ENTRY.  Whenever the label ENTRY is used in this particular source code, it will be referred to the information found at line 110.  Here are two ways in which the sample program may be used, both without and with labels:

------------------------------------------------------------
Example 2.                                                  
------------------------------------------------------------
    00100         ORG     5000H           ;DEC 20480
    00110 ENTRY   LD      HL,3C00H        ;VIDEO    
      :            :         :                  :   
      :    --- INTERVENING PROGRAM LINES ---    :   
      :            :         :                  :   
    04790         JP      5000H           ;TO ENTRY 
------------------------------------------------------------
    00100         ORG     5000H           ;DEC 20480
    00110 ENTRY   LD      HL,3C00H        ;VIDEO    
      :            :         :                  :   
      :    --- INTERVENING PROGRAM LINES ---    :   
      :            :         :                  :   
    04790         JP      ENTRY           ;TO ENTRY 
------------------------------------------------------------



Both these samples are identical -- this time.  But change the origin (ORG) in line 100 to 6000H, and line 4790 is suddenly incorrect in the first sample (because 4790 would be jumping to 5000H, when it should now be jumping to 6000H), but remains correct in the second sample (since the assembler will correctly evaluate the label ENTRY and produce the correct address).  Labels can go even further than that.  Here are two lines from the original listing:

------------------------------------------------------------
Example 3.                                                  
------------------------------------------------------------
    00110 ENTRY   LD      HL,3C00H        ;VIDEO   
    00120         LD      DE,3C01H        ;VIDEO+1 
------------------------------------------------------------

Now type I105 <ENTER>.  Line 00105 and a cursor will be presented, waiting for your input.  Type --

------------------------------------------------------------
Entry 2.                                                    
------------------------------------------------------------
    VIDEO<TAB>EQU<TAB>3C00H<TAB><TAB>;SCREEN<ENTER>
------------------------------------------------------------

-- and a NO ROOM BETWEEN LINES message will appear.  This is normal as line-numbering parameters currently stand in this example.  Line 105 has been accepted, but recall that the Insert-Line (I) command originally entered at Edtasm's initialization was used with this default value:  line 100 in increments of 10.  Therefore, the next possible line after 105 would be 115 -- which can't be squeezed in before line 110.  But if you had planned to insert lines 105, 106, 107, 108, and 109, you might have type I105,1 <ENTER> -- insert line 105 in increments of 1.

        Back to the example.  Now type P105:120 to list a few lines.  Your screen should display this information:

------------------------------------------------------------
Example 4.                                                  
------------------------------------------------------------
    00105 VIDEO   EQU     3C00H           ;SCREEN 
    00110 ENTRY   LD      HL,3C00H        ;VIDEO  
    00120         LD      DE,3C01H        ;VIDEO+1
------------------------------------------------------------

        This EQU is an important new feature, called an "equate" (equate is pronounced EE-kwate, and is a noun).  It is not a Z80 opcode.  Rather, as used in this sample, the EQU feature instructs the assembler itself to create a label called VIDEO, and make it equal to the value 3C00 hex.  Every time you as a programmer need 3C00 hex in this source program, you can simply write VIDEO.  Lines 110 and 120 may then be rewritten easily.  If you are familiar with BASIC's editing commands, you can edit the line by typing E110 <ENTER>.  Otherwise, merely retype the line by using the replace (R) command; here is a sample screen sequence:

------------------------------------------------------------
Screen 3.                                                   
------------------------------------------------------------
    *P105:120                                             
    00105 VIDEO   EQU     3C00H           ;SCREEN         
    00110 ENTRY   LD      HL,3C00H        ;VIDEO          
    00120         LD      DE,3C01H        ;VIDEO+1        
    *R110                                                 
    00110 ENTRY   LD      HL,VIDEO        ;VIDEO          
    NO ROOM BETWEEN LINES                                 
    *R120                                                 
    00120         LD      DE,VIDEO+1      ;VIDEO+1        
    NO ROOM BETWEEN LINES                                 
    *P105:120                                             
    00105 VIDEO   EQU     3C00H           ;SCREEN         
    00110 ENTRY   LD      HL,VIDEO        ;VIDEO          
    00120         LD      DE,VIDEO+1      ;VIDEO+1        
    *_                                                    
------------------------------------------------------------

        Other parts of the source listing should become clear.  The Edtasm semicolon (;) works like BASIC's remark (REM or ') command, and everything following it is ignored by the assembler.  Edtasm source lines consist entirely of comments preceded by the semicolon; this is important because good source code documentation suggest the liberal use of comments both on program lines and in explanatory blocks.


Saving and Loading with Edtasm
------------------------------

        The sample program presented in Screen 2 is a simple screen-whiting subroutine.  It can be saved to cassette in both the source code form and in a machine language form.  Saving Edtasm files to cassette is like saving in Level II BASIC, except that filenames may contain up to six characters instead of only one.  Insert a cassette into the tape recorder, set it to record, and type:

        W<b>CLEAR<ENTER>

The lowercase b in brackets <b> in a mandatory blank space.  In certain situations, Edtasm requires such a space, and writing to tape is one of those.  When this line is entered, a READY CASSETTE message will appear.  Press <ENTER>.  The tape will begin to move, and a leader followed by the source program will be written to tape.  Write it to tape several times to be sure the save is reliable, as you would with BASIC.

        Now it's time to discover that you've actually created something useful by entering this source program.  It will be converted to a machine-language program with the Assemble (A) command.  The Assemble command has several options, but these will be discussed later.  For the moment, merely type A<b>CLEAR<ENTER>.  After a very brief pause, the listing will flash by again, but in a new format.  Here is how it will look:

------------------------------------------------------------
Screen 4.                                                   
------------------------------------------------------------
5000          00100          ORG     5000H       ;DEC 20480 
3C00          00105 VIDEO    EQU     3C00H       ;SCREEN    
5000 21003C   00110 ENTRY    LD      HL,VIDEO    ;VIDEO     
5003 11013C   00120          LD      DE,VIDEO+1  ;VIDEO+1   
5006 01FF03   00130          LD      BC,03FFH    ;TOTAL SCRN
5009 36FF     00140          LD      (HL),255    ;BLOCK CHAR
500B EDB0     00150          LDIR                ;BLOCK MOVE
500D C9       00160          RET                 ;TO BASIC  
0000          00170          END                            
00000 TOTAL ERRORS                                          
                                                            
ENTRY   5000                                                
VIDEO   3C00                                                
READY CASSETTE                                              
_                                                           
------------------------------------------------------------

        There are two new columns in this display.  The first column is the hexadecimal memory addresses being used by the assembler while producing the machine code.  The second column is a hexadecimal rendition of the _actual_ _object_ _code_ being produced by Edtasm and readied to save on tape.

        You should already have a tape in the recorder ready to go.  Press the enter key.  The recorder starts, a leader is written, and a very short program (about 1/4 second) follows.  That short time is all that is needed to record the entire object code produced by the source listing on the screen!  Type A<b>CLEAR<ENTER> again, and save the object code on tape once more.  (Remember that the bracketed b <b> is a required black space).

        You now have a tape containing (1) several dumps of your original source code, with labels, line numbers, comments, etc., and (2) several dumps of an object code.  What do you do with the object code now?  Load it in SYSTEM format!  First exit Edtasm by typing B<ENTER>.  The Memory Size question will appear, to which you may respond with <ENTER>.   Next, type SYSTEM<ENTER>, and respond to the *? prompt with the name under which you saved the object code, CLEAR.  Rewind the tape to the beginning of the object code, and set it to play.  An asterisk will appear as usual in the right hand corner of the screen, but the loading will be completed in less than a second, and the *? prompt will return.  Tap BREAK.

        You now have a screen-white program loaded into memory.  Enter these lines --

        10 POKE 16526,0 : POKE 16527,80
        20 M=USR(0)
        30 GOTO 30

-- and RUN the program.  The POKE commands place an execution address in the USR(0) patch point; this feature will be discussed later.  The screen will white, and READY will return.  The object code works.  You have completed a machine language program with Edtasm.

        Here is a complete screen of what you have done since exiting Edtasm:

------------------------------------------------------------
Screen 5.                                                   
------------------------------------------------------------
        MEMORY SIZE? <ENTER>                          **
        RADIO SHACK LEVEL II BASIC                      
        READY                                           
        >SYSTEM <ENTER>                                 
                                                        
        *? CLEAR <ENTER>                                
                                                        
        *? <BREAK>                                      
        READY                                           
        >10 POKE 16526,0 : POKE 16527,80 <ENTER>        
        >20 M=USR(0) <ENTER>                            
        >30 GOTO 30 <ENTER>                             
        RUN <ENTER>                                     
------------------------------------------------------------

        Now reload Edtasm according to the instructions.  It is not possible to load the object code itself back into the Edtasm buffer; only the source code may be loaded.  To do so, type L<b>CLEAR<ENTER>, rewind the tape, and set it to play.  When the source code is found, it will load into Edtasm's buffer, flashing the asterisks as usual in the upper right corner of the screen.  The star (*) prompt will return when loading is complete, and you may print the entire listing on the screen by using the command P#:* <ENTER>.


Saving and Loading with the Apparat Edtasm
------------------------------------------

        With its NEWDOS disc operating system, Apparat provided disc input/output routines to Edtasm.  It also removed the default features of the tape-based Edtasm.  Among the command differences:

W<b>NAME is replaced with the format WT=NAME in order to
        record a source tape.

L<b>NAME is replaced with the format LT=NAME in order to
        reload a recorded source tape.

WD=NAME writes a source file to disc.  The disc directory
        is searched for the filename, and if one is found,
        you are prompted with:
        ----------------------------------------------------
        FILE ALREADY EXISTS.  USE IT????
        _                               
        ----------------------------------------------------
        to which you enter Y to do so, or any other key to
        return the (*) prompt.  If the directory search
        does not turn up a matching filename, you are
        prompted with
        ----------------------------------------------------
        FILE NON-EXISTENT. REPLY "C" TO CREATE IT     
        _                                             
        ----------------------------------------------------
        Responding with a C creates the new file and saves
        the source code; responding with any other letter
        returns the (*) prompt.

LD=NAME loads a source file from disc.  Before loading, 
        however, it checks the source buffer to see if code
        is already present, in which case it will prompt
        you with:
        ----------------------------------------------------
        TEXT IN BUFFER. ARE YOU CONCATENATING????
        _                                        
        ----------------------------------------------------
        If you wish to append the new file to the old, you
        would respond Y; otherwise, the old buffer will be
        wiped clear before the new source code is loaded.

A<b>NAME immediately presents the question:
        ----------------------------------------------------
        OBJECT FILE TO DISK OR TAPE?  REPLY "D" OR "T".
        _                                              
        ----------------------------------------------------
        Responding T gives control over to the normal tape
        procedures.  Responding D calls up the question --
        ----------------------------------------------------
        OBJECT FILESPEC?                                   
        _                                                  
        ----------------------------------------------------
        -- which incurs a file check, and the same sequence
        used for WD=NAME (above) is followed.

Note that programs written with the disc-based Edtasm must not conflict with disc parameters.  A suggested alternate origin (ORG) address for test programs in this manual is 7000H.


Editing Lines
-------------

        There are 11 editing commands, with the same characteristics as those used in Level II BASIC.  To begin a line edit in Edtasm, type E. (to edit the current line), E100 (to edit line 100), E# (to edit the first line), E* (to edit the last line).  The line number will be presented, with the cursor in the first position:

                *E100 <ENTER>                   
                00100_                          

The space bar and backspace move the cursor across the line to be edited.  n<Space> moves the cursor n spaces ahead (for example, 6<Space> moves the cursor 6 spaces ahead).  The following editing commands are available, listed in order of their most frequent use.  All are activated _without_ pressing the <ENTER> key.  The <ENTER> key is used only when editing is complete.

L     : Lists the line being edited, and moves the cursor
List  : below it on the screen, positioned in the first
Line  : edit slot.  L may be used at any time in the line
      : being edited to show the present status of that line.
        ----------------------------------------------------
        Screen 5a.  Showing the screen after typing L (Line)
        ----------------------------------------------------
        *E110 <ENTER> <enters the edit mode>            
        00110_ <waiting for edit command> <type L>      
        00110 ENTRY  LD    HL,VIDEO     ;VIDEO          
        00110_                                          
        ----------------------------------------------------

I     : Inserts characters at the cursor position.  Insert is
Insert: terminated by <ENTER>, which will effect the changes
      : in the line, or Escape <SHIFT-UP ARROW> (see below
      : for a description of Escape).
        ----------------------------------------------------
        Screen 5b.  Showing the screen in Insert mode       
        ----------------------------------------------------
        *E110 <ENTER> <enters the edit mode>              
        00110_ <space over to the end of VIDEO>           
        00110 ENTRY  LD    HL,VIDEO<I typed here>+1<ENTER>
        *P. <ENTER> <prints the current line>             
        00110 ENTRY  LD    HL,VIDEO+1   ;VIDEO            
        *_                                                
        ----------------------------------------------------

X     : Moves cursor to the end of the line, and goes into
Extra : the insert mode.  Like Insert (I), it is terminated
Insert: by <ENTER> or Escape.
        ----------------------------------------------------
        Screen 5c.  Showing the screen in Extra-Insert Mode
        ----------------------------------------------------
        *E110 <ENTER> <enters the edit mode>              
        00110_ <type X> <enters the extra-insert mode>    
        00110 ENTRY  LD    HL,VIDEO+1   ;VIDEO_           
        <typing additional characters>                    
        00110 ENTRY  LD    HL,VIDEO+1   ;VIDEO+1<ENTER>   
        *P. <ENTER> <prints the current line>             
        00110 ENTRY  LD    HL,VIDEO+1   ;VIDEO+1          
        *_                                                
        ----------------------------------------------------

H     : Hack and Insert mode, whereby the line to the 
Hack  : right of the cursor is deleted, and Edtasm goes
and   : into the Insert mode.  It is terminated with
Insert: <ENTER> or Escape.
        ----------------------------------------------------
        Screen 5d.  Screen demonstrating Hack-and-Insert  
        ----------------------------------------------------
        *E110 <ENTER> <enters the edit mode>             
        00110_ <space over to semicolon>                 
        00110 ENTRY  LD    HL,VIDEO+1   ;<type H>        
        <typing additional characters>                   
        00110 ENTRY  LD    HL,VIDEO+1   ;SCREEN+1 <ENTER>
        *P. <ENTER> <prints the current line>            
        00110 ENTRY  LD    HL,VIDEO+1   ;SCREEN+1        
        *_                                               
        ----------------------------------------------------

D     : Delete-character command.  This is referred to in
Delete: the Edtasm user's manual as "nD", meaning that any
      : number of characters may be deleted by prefacing
      : the letter D with a number.  For example, D alone
      : will delete a single character; 15D will delete 15
      : characters following the cursor.  Note that none of
      : these command characters is actually printed on the
      : screen; they are accepted by the edit function, so
      : if you get into trouble with too many deleted
      : characters due to keybounce, you should escape the
      : edit function and start again (see Escape and Q).
      : Unlike Level II BASIC, the D command does _not_ 
      : enclose the deleted material in points (such as FOR
      : X = !123!34 TO 16).
        ----------------------------------------------------
        Screen 5e.  Screen showing use of D and nD command
                    together with I (insert) command      
        ----------------------------------------------------
        *E110 <ENTER> <enters the edit mode>            
        00110_ <space over to VIDEO>                    
        00110 ENTRY  LD   HL,_  <waiting for edit cmd>  
        <type D><ENTER>IDEO     ;VIDEO+1                
        *P. <prints the current line>                   
        00110 ENTRY  LD   HL,IDEO     ;VIDEO+1          
        *E. <enters edit mode at current line>          
        00110_ <space over to IDEO>                     
        00110 ENTRY  LD   HL,_  <waiting for edit cmd>  
        <type 4D, type I, type>HERE<ENTER> ;VIDEO+1     
        *P. <ENTER> <prints the current line>           
        00110 ENTRY  LD   HL,HERE       ;VIDEO+1        
        *_                                              
        ----------------------------------------------------

C     : Change character command.  Like D, this can be
Change: written nC, where n indicates the number of
      : characters to be changed.  For example, C deletes
      : a single character; 7C changes seven characters.
      : Also like the nD command, the nC command does not
      : print the command quantity (such as 11C) on the
      : screen.  C is a curious command, because if too
      : many numbers are pressed before C (due to keybounce,
      : for example), the edit function will expect all
      : those characters to be typed -- including a carriage
      : return if you attempt to enter the line!         ----------------------------------------------------
        Screen 5f.  Demonstration of C and nC commands,
                    together with the Insert (I) command
        ----------------------------------------------------
        *E110 <ENTER> <enters the edit mode>            
        00110_  <waiting for edit command>              
        <space over to HERE>                            
        00110 ENTRY  LD   HL,_  <waiting for edit cmd>  
        <type 4C, type SCRN><ENTER>  ;VIDEO+1           
        *P. <prints the current line>                   
        00110 ENTRY  LD   HL,SCRN    ;VIDEO+1           
        *E. <enters edit mode on current line>          
        00110_  <waiting for edit command>              
        <space over to the N in SCRN>                   
        00110 ENTRY  LD   HL,SCR_ <waiting for edit cmd>
        <type C, type E, type I, type N><ENTER> ;VIDEO+1
        *P. <prints the current line>                   
        00110 ENTRY  LD   HL,SCREN    ;VIDEO+1          
        *_                                              
        ----------------------------------------------------

S     : Search for character.  Also, nSs to search for the
Search: nth occurrence of character s.  SQ searches for the
      : letter Q; 7SX searches for the 7th occurrence of the
      : letter X.
        ----------------------------------------------------
        Screen 5g.  Use of Search for Character command
        ----------------------------------------------------
        *E110 <ENTER> <enters the edit mode>            
        00110_ <waiting for edit command>               
        <enter SV>                                      
        00110 ENTRY  LD    HL,SCREN    ;_               
        <ENTER>                                         
        *P. <prints the current line>                   
        00110 ENTRY  LD    HL,SCREN    ;VIDEO+1         
        *_                                              
        ----------------------------------------------------

K     : Character search-and-destroy.  The format is 
Kill  : nKs, meaning kill all characters up to the nth
      : occurrence of character s.   Similar to the nD
      : command, nKs is more convenient for large groups
      : of characters to be deleted where you do not want
      : to count them.
        ----------------------------------------------------
        Screen 5h.  Example of search-and-destroy command
        ----------------------------------------------------
        *E110 <ENTER> <enters the edit mode>            
        00110_ <waits for edit command>                 
        <type 1KY to kill characters up to first Y>     
        <ENTER>Y  LD    HL,SCREN     ;VIDEO+1           
        *P. <prints the current line>                   
        00110 Y   LD    HL,SCREN     ;VIDEO+1           
        *_                                              
        ----------------------------------------------------

Escape: SHIFT-UP ARROW.  The up arrow is in the "escape"
      : position on a normal ASCII keyboard.  Any editing
      : mode (such as Insert, Hack-and-Insert, Extra, etc.)
      : can be exited with Escape.  For example, to make
      : several insertions in the same line:  Insert mode is
      : entered and characters are inserted; Escape is made;
      : the cursor is moved ahead or back; Insert mode is
      : entered again and characters are inserted; Escape is
      : made; and so forth.  This command is especially handy
      : when unusual errors have been made during a line
      : edit.  In this latter situation it goes hand-in-hand
      : with the Q command (see below).
        ----------------------------------------------------
        Screen 5i.  Using Escape with Insert and Insert-Extra
        ----------------------------------------------------
        *E110 <ENTER> <enters the edit mode>            
        00110_ <waiting for edit command>               
        <type I, type>ENTR<Escape><type X, type>LOCATION
        <ENTER>                                         
        *P. <prints the current line>                   
        00110 ENTRY  LD    HL,SCREN   ;VIDEO+1 LOCATION 
        *_                                              
        ----------------------------------------------------

Q     : Quit editing.  Always use Escape (above) to make sure
Quit  : you are out of any edit submode before pressing Q.
Edit  : This will then exit the editing mode with _no_
      : changes made.  In any situation where a crucial line
      : is being edited, and you are unsure if you have made
      : changes correctly, use Q.  The line may be restarted
      : with E., or left as is.
        ----------------------------------------------------
        Screen 5j.  Example of Quitting an edit.
        ----------------------------------------------------
        *E110 <ENTER> <enters the edit mode>            
        00110_ <waiting for edit command>               
        <type 4KV, which will kill all characters up to 
        the 4th occurence of the letter V.  Since there 
        is only one letter V, this means all characters 
        in the line will be killed>                     
        <type I, for Insert.  At this point you want to 
        exit edit mode because you don't want to use the
        editing you have just typed.>                   
        <type SHIFT-UP ARROW, which is Escape>          
        <type Q>                                        
        *P. <prints current line>                       
        00110 ENTRY  LD    HL,SCREN   ;VIDEO+1 LOCATION 
        *_                                              
        ------------------------------------------------

E     : Enter the changes.  Performs the same function as
Enter : pressing the <ENTER> key.

A     : Restarts the editing process.  Like Q in that all
Again : editing up to that point is canceled.  This is one
      : of the least frequently used edit functions because
      : Q covers its function and also provides reassurance
      : that the editing process has been terminated safely.


                     Part Three                         

                Dennis Bathory Kitsz                    


---------------------------------------------------------
Note:  There were several layout errors in Part Two which seriously affected clarity.  Examples 5, 6, 7 and 8 were referenced in the text, but improperly captioned as Figures 2, 3, 4 and 5.  Furthermore, Example 6 ("Figure 4") on page 19 was set out as two columns, but without a divider, causing it to look like one column.  Some long-distance terminal program incompatibilities dropped out tab characters, causing Example 8 ("Figure 5") to contain irregular rows of comments and uncentered columns; readers should be assured that this is not the way they should look.  The symbol table was also missing from this example.  On page 12, Zilog's address should have been Bubb Road, and on the facing page, Figure 1 had a missing line from "Is it a Break?" (column three) back to "Clear Screen" (column one).
---------------------------------------------------------



What separates an assembler from merely a sophisticated monitor/debugger is its level of convenience:  beyond merely assembling portions of binary code from mnemonics (which all good monitors can do), it adjusts, changes, alters, saves and recalls.  This section of the Editor/Assembler manual will cover expressions (arithmetic and logical functions including left and right shifts), the few assembler directives, and some minor conveniences.  Finally, hidden Z80 instructions will be explained, together with a simple method of including these -- since they are used by Z80 programmers and now guaranteed by Zilog as functional codes.


Expressions
-----------

        Usual human communication is by relationship, and likewise Editor/Assembler activities can be handled this way.  If your someone comes knocking at your door asking for your neighbor John Jones, you will probably tell the caller he lives next door, rather than "he lives at 97 Plum Street".  Similarly, a screen address identified with the label VIDEO will suggest other relative locations -- VIDEO+64 for the next line down, VIDEO+1 for the next character, VIDEO-1 for the previous character.

        Edtasm supports these functions, and others; they are called "expressions".  Their value is indisputable; some examples have already contained expressions.  Look at Example 9.

--------------------------------------------------------
Example 9.  Using Expressions for Clarity.              
--------------------------------------------------------
3C00            0100    VIDEO   EQU     15360D          
03FF            0110    COUNT   EQU     1024D           
0020            0120    ASCII   EQU     0               
06CC            0130    BASIC   EQU     1740D           
5000            0140            ORG     20480D          
5000   21003C   0150    BLACK   LD      HL,VIDEO        
5003   11013C   0160            LD      DE,VIDEO+1      
5006   01FF03   0170            LD      BC,COUNT-1      
5009   3620     0180            LD      (HL),ASCII+32   
500B   EDB0     0190            LDIR                    
500D   C9       0200            RET                     
500E   21003C   0210    WHITE   LD      HL,VIDEO        
5011   11013C   0220            LD      DE,VIDEO+1      
5014   01FF03   0230            LD      BC,COUNT-1      
5017   36BF     0240            LD      (HL),ASCII+191  
5019   EDB0     0250            LDIR                    
501B   C9       0260            RET                     
501C   21007C   0270    BUILD   LD      HL,VIDEO+4000H  
501F   11003C   0280            LD      DE,VIDEO        
5022   010004   0290            LD      BC,COUNT        
5025   EDB0     0300            LDIR                    
5027   C9       0310            RET                     
06CC            0320            END     BASIC           
--------------------------------------------------------

This short example demonstrates the additional clarity introduced by + and - expressions together with labels.  In both BLACK and WHITE screen-fill modes, the location of the filling and the total count are identical.  Even though defining ASCII as 0 seems irrelevant, the neat part is that a command like LD HL,ASCII+191 states clearly that a character is to be placed in memory.  VIDEO+4000H suggests a matching screen image somewhere in high memory.

        The logical function AND is represented by an ampersand (&), and a logical shift is represented by a less-than symbol (<).  Here's a typical problem and its solution:  A program is being created, and the location of a major routine (called, for argument, BLATT) is shifting as the program develops.  Later in the program, a storage area pointed to by the IY register keeps the current address of BLATT and other selected routines available for use by other program pointers.  How is BLATT's address used put into storage, byte by byte, if it keeps changing?

        Example 10 shows two typical excerpts, BLATT's current location and the area pointed to by IY, with offset bytes BLATHI and BLATLO.

--------------------------------------------------------
Example 10.  Using Logical AND, Logical Shift           
--------------------------------------------------------
<THE FOLLOWING EQUATES INDICATE HIGH & LOW OFFSET BYTES 
0004            00220   BLATHI  EQU     4               
0005            00230   BLATLO  EQU     5               
<<<THE PROGRAM IS PICKED UP WHERE BLATT IS IDENTIFIED>>>
3173  C35204    02190           JP      0452H           
                02200   ; CHECK FOR STATUS OF STACK     
3176            02210   BLATT   EQU     $               
3176  E3        02220   BEGIN   EX      (SP),HL         
3177  7D        02230           LD      A,L             
<<<THE PROGRAM CONTINUES FOR SEVERAL HUNDRED LINES>>>   
3486  200C      07170           JR      NZ,IIII         
                07180   ; PLACE LOCATION IN PATCH ROW   
3488  FD360476  07190           LD      (IY+BLATHI),BLATT&0FFH
348C  FD360531  07200           LD      (IY+BLATLO),BLATT&0FF00H<-8
3490  E1        07210           POP     HL              
<<<THE PROGRAM CONTINUES WITH OTHER PATCHPOINT USES>>>  
--------------------------------------------------------

        There is something formidable about a phrase like "LD (IY+BLATLO),BLATT&0FF00<-8".  But in fact, it reveals a great deal more than its equivalent in this instance, "LD (IY+5),31H".  The latter says quite clearly, "Load register IY offset +5 with value 31H".  But what does that mean?  More reasonable is the former, complicated looking example, which states, "Load register IY, offset by byte position BLATLO, with address BLATT, logically ANDed with 0FF00H (to strip off the low byte) and shifted left -8 bit positions, i.e., shifted right +8 positions, resulting in the creation of the most significant byte in the BLATT address."

        Notice two things.   First, in Line 7200, the shift symbol means shift LEFT; in order to shift bits to the right, a negative value must be used.  When using this command, also remember that it is shifting _bits_, exactly like the Z80 shift and rotate opcodes.  That is, 3456 shifted one bit left is not _4563_.  It is instead 0011010001010110 shifted left (0110100010101100), that is, 68AC.  To achieve 4563, it must be shifted left four positions (0100010101100011).  Second, in Line 2210, BLATT EQU $.  The symbol $ indicates "current address being assembled."  This in effect makes BLATT a variable equate, always sticking out for all to see, and always available for changing at every re-assembly of the program.

        The $ symbol has a more popular use in the assembly of relative branches (opcode JR).  Since JR opcodes are so often used, the continuous application of labels to such simple elements as loops uses up enormous quantities of memory available to Edtasm during both entry and assembly.  Space is used for the label, and space is set aside when the symbol table is created.

        Look at Examples 11 and 12.  These are two different versions of the same program, a simple delay.  However, the first example uses labels for loops that will be used only once.  The second example replaces them with "current address with offset", $-? and $-?.

--------------------------------------------------------
Example 11.  Relative Branches Using Labels for Offset. 
--------------------------------------------------------

500D  0605      00180           LD      B,5             
500F  21FFFF    00190   LOOP1   LD      HL,0FFFFH       
5012  2B        00200   LOOP2   DEC     HL              
5013  7C        00210           LD      A,H             
5014  B5        00220           OR      L               
5015  20FB      00230           JR      NZ,LOOP2        
5017  10F6      00240           DJNZ    LOOP1           
5019  C9        00250           RET                     
--------------------------------------------------------

--------------------------------------------------------
Example 12.  Relative Branches Using Offset with $.     
--------------------------------------------------------
500D  0605      00180           LD      B,5             
500F  21FFFF    00190           LD      HL,0FFFFH       
5012  2B        00200           DEC     HL              
5013  7C        00210           LD      A,H             
5014  B5        00220           OR      L               
5015  20FB      00230           JR      NZ,$-3          
5017  10F6      00240           DJNZ    $-8             
5019  C9        00250           RET                     
--------------------------------------------------------

        The clarity of Example 11, however, should only give way to the memory economy of Example 12 when BUFFER FULL or SYMBOL TABLE OVERFLOW messages appear.  In such a case, be extremely careful when removing labels.  Use the "F" command to find each occurrence of the symbol you wish to delete, and consider if its loss will confuse future program updates.  Be sure to mark such locations on a printed version of the program.


Pseudo-Ops Revisited
--------------------

        The most common assembler directives (pseudo-operands, or pseudo-ops) have already been discussed:  ORG and EQU, with some mention of the variants of DEF.

        Individual bytes may be defined by using the DEFB pseudo-op.  DEFB 38H assigns the value 38 hex to the current location being assembled.  When ASCII characters are being defined, it is often clearer and more convenient to place the character itself in single quotes, as DEFB "8" -- which produces the same results as DEFB 38H.

        In Z80 notation, the least significant byte of the address is obtained by the processor before the most significant byte.  This can be confusing when writing a program, particularly when properly configured two-byte address information must be conveyed.  For this purpose the DEFW (define word) instruction is used.  DEFW 3C00H defines address 3C00 in Z80 format, that is, 00 followed by 3C.

        DEFS reserves a string of unused memory beginning at the current location being assembled.  This is useful in determining the approximate "layout" of a program beforehand, and in reserving space for tables, messages, additional subroutines, or other program material which must be completed later.  Furthermore, it can be used to set aside a work area or vector table for use by the final working program.

        Finally, DEFM creates the block of hex code representing the ASCII message; this has already been demonstrated.

        Example 13 shows how these DEF pseudo-ops are used.

--------------------------------------------------------
Example 13.  Using DEF Pseudo-Ops.                      
--------------------------------------------------------
0000  20        00010           DEFB    20H     
0001  45        00020           DEFB    'E'     
0002  003C      00030           DEFW    3C00H   
0004  CC06      00040           DEFW    06CCH   
0006            00050           DEFS    20H     
0026  41        00060           DEFM    'ABCDE' 
002B            00070           END             
--------------------------------------------------------

        The END pseudo-op has two functions:  to tell the assembler that the assembly is to be concluded, and to provide a starting (transfer) address for the program.  The default address (END) is 0000.  END 06CCH will transfer control (when a system tape is loaded and the *? prompt reappears) to a Basic "Ready" if a slash (/) is entered.


Assembler Commands
------------------

        The full-featured Zilog assembler contains a number of assembler commands; however, this reduced Edtasm from Radio Shack contains only two:  *LIST OFF and *LIST ON.  These are handy debugging tools, in that assembly is suspended when *LIST OFF is encountered (it must be in the first column and the source code and begin with an asterisk), and assembly is resumed when *LIST ON is encountered.  This makes temporary partial assembly of sections of source code possible; it saves a great deal of time when assembling long programs.

        On unmodified versions of Edtasm, *LIST OFF can be placed immediately before a block of ASCII text.  This will prevent a stream of ASCII code from being printed with every message.  *LIST ON can be placed immediately after the line containing the DEFM command.






--------------------------------------------------------
                     Appendix II                        
           Index to Editor/Assembler Opcodes            
--------------------------------------------------------

                        KEY:
           r = A, B, C, D, E, H, or L
           n = one-byte expression 0 to +255
           d = one-byte expression -128 to +127
           b = one-byte expression 0 to +7
           e = one-byte expression -126 to +129
          NN = two-byte expression 0 to 65535

--------------------------------------------------------
Some instructions are shown in both one- and two-byte   
versions.  The two-byte versions are usually by default 
of a generic opcode; the one-byte versions provide      
identical results but save memory and execution time.   
--------------------------------------------------------
* Indicates undocumented opcode; refer to "Undocumented 
Z80 Opcodes" by Daniel R. Lunsford (see The Alternate   
Source, I:6, for details of their operation and use).   
Suggested Editor/Assembler byte and/or opcode entry     
combinations are shown.                                 
 Key to undocumented opcodes:                           
 HX = High byte IX register, LX = Low byte IX register. 
 HY = High byte IY register, LY = Low byte IY register. 
 SLS = Shift left and set LSB = 1.                      
--------------------------------------------------------

    Mnemonic        Edtasm Page             Zilog Page
-----------------   -----------             ----------

ADC     A,(HL)          44                      108
ADC     A,(IX+d)        46                      108
ADC     A,(IY+d)        46                      108
ADC     A,r             46                      108
ADC     A,n             46                      108
ADC     A,HX            *DEFB 0DDH + ADC A,H    ---
ADC     A,LX            *DEFB 0DDH + ADC A,L    ---
ADC     A,HY            *DEFB 0FDH + ADC A,H    ---
ADC     A,LY            *DEFB 0FDH + ADC A,L    ---
ADC     HL,BC           63                      149
ADC     HL,DE           63                      149
ADC     HL,HL           63                      149
ADC     HL,SP           63                      149

ADD     A,(HL)          44                      103
ADD     A,(IX+d)        44                      104
ADD     A,(IY+d)        45                      106
ADD     A,r             43                      100
ADD     A,n             43                      102
ADD     A,HX            *DEFB 0DDH + ADD A,H    ---
ADD     A,LX            *DEFB 0DDH + ADD A,L    ---
ADD     A,HY            *DEFB 0FDH + ADD A,H    ---
ADD     A,LY            *DEFB 0FDH + ADD A,L    ---
ADD     HL,BC           63                      147
ADD     HL,DE           63                      147
ADD     HL,HL           63                      147
ADD     HL,SP           63                      147
ADD     IX,BC           64                      153
ADD     IX,DE           64                      153
ADD     IX,IX           64                      153
ADD     IX,SP           64                      153
ADD     IY,BC           65                      155
ADD     IY,DE           65                      155
ADD     IY,IY           65                      155
ADD     IY,SP           65                      155

AND     (HL)            49                      114
AND     (IX+d)          49                      114
AND     (IY+d)          49                      114
AND     r               49                      114
AND     n               49                      114
AND     HX              *DEFB 0DDH + AND H      ---
AND     LX              *DEFB 0DDH + AND L      ---
AND     HY              *DEFB 0FDH + AND H      ---
AND     LY              *DEFB 0FDH + AND L      ---

BIT     b,r             81                      203
BIT     b,(HL)          81                      205
BIT     b,(IX+d)        82                      207
BIT     b,(IY+d)        82                      209

CALL    C,NN            93                      240
CALL    M,NN            93                      240
CALL    NC,NN           93                      240
CALL    NN              92                      238
CALL    NZ,NN           93                      240
CALL    P,NN            93                      240
CALL    PE,NN           93                      240
CALL    PO,NN           93                      240
CALL    Z,NN            93                      240

CCF                     58                      137

CP      (HL)            52                      120
CP      (IX+d)          52                      120
CP      (IY+d)          52                      120
CP      r               52                      120
CP      n               52                      120
CP      HX              *DEFB 0DDH + CP H       ---
CP      LX              *DEFB 0DDH + CP L       ---
CP      HY              *DEFB 0FDH + CP H       ---
CP      LY              *DEFB 0FDH + CP L       ---

CPD                     42                       95
CPDR                    42                       97
CPI                     41                       91
CPIR                    41                       93

CPL                     57                      134

DAA                     56                      132

DEC     (HL)            55                      129
DEC     (IX+d)          55                      129
DEC     (IY+d)          55                      129
DEC     r               55                      129
DEC     HX              *DEFB 0DDH + DEC H      ---
DEC     LX              *DEFB 0DDH + DEC L      ---
DEC     HY              *DEFB 0FDH + DEC H      ---
DEC     LY              *DEFB 0FDH + DEC L      ---
DEC     BC              67                      160
DEC     DE              67                      160
DEC     HL              67                      160
DEC     IX              67                      161
DEC     IY              68                      162
DEC     SP              67                      160

DI                      60                      141

DJNZ    e               91                      235

EI                      60                      142

EX      (SP),HL         35                       80
EX      (SP),IX         36                       81
EX      (SP),IY         36                       82
EX      AF,AF'          34                       78
EX      DE,HL           34                       77
EXX                     35                       79

HALT                    59                      140

IM      0               61                      143
IM      1               61                      144
IM      2               62                      145

IN      A,(n)           98                      253
IN      r,(C)           98                      254

INC     (HL)            53                      124
INC     (IX+d)          54                      125
INC     (IY+d)          54                      127
INC     r               53                      122
INC     HX              *DEFB 0DDH + INC H      ---
INC     LX              *DEFB 0DDH + INC L      ---
INC     HY              *DEFB 0FDH + INC H      ---
INC     LY              *DEFB 0FDH + INC L      ---
INC     BC              65                      157
INC     DE              65                      157
INC     HL              65                      157
INC     SP              65                      157
INC     IX              66                      158
INC     IY              66                      159

IND                    101                      260
INDR                   102                      262
INI                     99                      256
INIR                   100                      258

JP      (HL)            89                      232
JP      (IX)            90                      233
JP      (IY)            90                      234
JP      C,NN            86                      221
JP      M,NN            86                      221
JP      NC,NN           86                      221
JP      NN              86                      220
JP      NZ,NN           86                      221
JP      P,NN            86                      221
JP      PE,NN           86                      221
JP      PO,NN           86                      221
JP      Z,NN            86                      221

JR      C,e             87                      224
JR      e               87                      223
JR      NC,e            88                      226
JR      NZ,e            89                      230
JR      Z,e             88                      228

LD      (BC),A          20                       45
LD      (DE),A          20                       46
LD      (HL),r          15                       34
LD      (HL),n          17                       39
LD      (IX+d),r        16                       35
LD      (IX+d),n        17                       40
LD      (IY+d),r        16                       37
LD      (IY+d),n        18                       41
LD      (NN),A          21                       47
LD      (NN),BC         28                       62
LD      (NN),DE         28                       62
LD      (NN),HL         29 (1-byte version)      61
LD      (NN),HL         28 (2-byte version)      62
LD      (NN),IX         28                       64
LD      (NN),IY         29                       65
LD      (NN),SP         28                       62
LD      A,(BC)          18                       42
LD      A,(DE)          19                       43
LD      A,(HL)          14                       29
LD      A,(IX+d)        14                       30
LD      A,(IY+d)        15                       32
LD      A,(NN)          19                       44
LD      A,r             13                       27
LD      A,n             13                       28
LD      A,I             21                       48
LD      A,R             22                       49
LD      A,HX            *DEFB 0DDH + LD A,H     ---
LD      A,HY            *DEFB 0FDH + LD A,H     ---
LD      A,LX            *DEFB 0DDH + LD A,L     ---
LD      A,LY            *DEFB 0FDH + LD A,L     ---

LD      B,(HL)          14                       29
LD      B,(IX+d)        14                       30
LD      B,(IY+d)        15                       32
LD      B,r             13                       27
LD      B,n             13                       28
LD      B,HX            *DEFB 0DDH + LD B,H     ---
LD      B,HY            *DEFB 0FDH + LD B,H     ---
LD      B,LX            *DEFB 0DDH + LD B,L     ---
LD      B,LY            *DEFB 0FDH + LD B,L     ---
LD      BC,(NN)         26                       57
LD      BC,NN           24                       53

LD      C,(HL)          14                       29
LD      C,(IX+d)        14                       30
LD      C,(IY+d)        15                       32
LD      C,r             13                       27
LD      C,n             13                       28
LD      C,HX            *DEFB 0DDH + LD C,H     ---
LD      C,HY            *DEFB 0FDH + LD C,H     ---
LD      C,LX            *DEFB 0DDH + LD C,L     ---
LD      C,LY            *DEFB 0FDH + LD C,L     ---

LD      D,(HL)          14                       29
LD      D,(IX+d)        14                       30
LD      D,(IY+d)        15                       32
LD      D,r             13                       27
LD      D,n             13                       28
LD      D,HX            *DEFB 0DDH + LD D,H     ---
LD      D,HY            *DEFB 0FDH + LD D,H     ---
LD      D,LX            *DEFB 0DDH + LD D,L     ---
LD      D,LY            *DEFB 0FDH + LD D,L     ---
LD      DE,(NN)         26                       57
LD      DE,NN           24                       53

LD      E,(HL)          14                       29
LD      E,(IX+d)        14                       30
LD      E,(IY+d)        15                       32
LD      E,r             13                       27
LD      E,n             13                       28
LD      E,HX            *DEFB 0DDH + LD E,H     ---
LD      E,HY            *DEFB 0FDH + LD E,H     ---
LD      E,LX            *DEFB 0DDH + LD E,L     ---
LD      E,LY            *DEFB 0FDH + LD E,L     ---

LD      H,(HL)          14                       29
LD      H,(IX+d)        14                       30
LD      H,(IY+d)        15                       32
LD      H,r             13                       27
LD      H,n             13                       28
LD      HX,r            *DEFB 0DDH + LD H,r     ---
                         (except H or L)           
LD      HY,r            *DEFB 0FDH + LD H,r     ---
                         (except H or L)           
LD      HX,n            *DEFB 0DDH + LD H,n     ---
LD      HY,n            *DEFB 0FDH + LD H,n     ---
LD      HX,LX           *DEFB 0DDH + LD H,L     ---
LD      HY,LY           *DEFB 0FDH + LD H,L     ---
LD      HL,(NN)         25 (1-byte version)      56
LD      HL,(NN)         26 (2-byte version)      57
LD      HL,NN           24                       53

LD      I,A             22                       50

LD      IX,(NN)         26                       59
LD      IX,NN           24                       54
LD      IY,(NN)         27                       60
LD      IY,NN           25                       55

LD      L,(HL)          14                       29
LD      L,(IX+d)        14                       30
LD      L,(IY+d)        15                       32
LD      L,r             13                       27
LD      L,n             13                       28
LD      LX,r            *DEFB 0DDH + LD L,r     ---
                         (except H and L)          
LD      LY,r            *DEFB 0FDH + LD L,r     ---
                         (except H and L)          
LD      LX,n            *DEFB 0DDH + LD L,n     ---
LD      LY,n            *DEFB 0FDH + LD L,n     ---
LD      LX,HX           *DEFB 0DDH + LD L,H     ---
LD      LY,HY           *DEFB 0FDH + LD L,H     ---

LD      R,A             23                       51

LD      SP,(NN)         26                       57
LD      SP,HL           29                       66
LD      SP,IX           30                       67
LD      SP,IY           30                       68
LD      SP,NN           24                       53

LDD                     39                       87
LDDR                    40                       89
LDI                     37                       83
LDIR                    38                       85

NEG                     57                      135

NOP                     59                      139

OR      (HL)            50                      116
OR      (IX+d)          50                      116
OR      (IY+d)          50                      116
OR      r               50                      116
OR      n               50                      116
OR      HX              *DEFB 0DDH + OR H       ---
OR      LX              *DEFB 0DDH + OR L       ---
OR      HY              *DEFB 0FDH + OR H       ---
OR      LY              *DEFB OFDH + OR L       ---

OTDR                   107                      273
OTIR                   105                      269
OUT     (C),r          103                      265
OUT     (n),A          103                      264
OUTD                   106                      271
OUTI                   104                      267

POP     AF              32                       72
POP     BC              32                       72
POP     DE              32                       72
POP     HL              32                       72
POP     IX              33                       74
POP     IY              33                       75

PUSH    AF              31                       69
PUSH    BC              31                       69
PUSH    DE              31                       69
PUSH    HL              31                       69
PUSH    IX              31                       70
PUSH    IY              32                       71

RES     b,(HL)          85                      217
RES     b,(IX+d)        85                      217
RES     b,(IY+d)        85                      217
RES     b,r             85                      217

RET                     94                      243
RET     C               95                      244
RET     M               95                      244
RET     NC              95                      244
RET     NZ              95                      244
RET     P               95                      244
RET     PE              95                      244
RET     PO              95                      244
RET     Z               95                      244
RETI                    96                      246
RETN                    96                      248

RL      (HL)            73                      180
RL      (IX+d)          73                      180
RL      (IY+d)          73                      180
RL      r               73                      180
RL      A               73 (2-byte version)     180
RLA                     69 (1-byte version)     166
RLC     (HL)            71                      174
RLC     (IX+d)          72                      176
RLC     (IY+d)          72                      178
RLC     r               71                      172
RLC     A               71 (2-byte version)     172
RLCA                    69 (1-byte version)     164
RLD                     79                      198

RR      (HL)            75                      186
RR      (IX+d)          75                      186
RR      (IY+d)          75                      186
RR      r               75                      186
RR      A               75 (2-byte version)     186
RRA                     70 (1-byte version)     170
RRC     (HL)            74                      183
RRC     (IX+d)          74                      183
RRC     (IY+d)          74                      183
RRC     r               74                      183
RRC     A               74 (2-byte version)     183
RRCA                    70 (1-byte version)     168
RRD                     80                      200

RST     00H             97                      250
RST     08H             97                      250
RST     10H             97                      250
RST     18H             97                      250
RST     20H             97                      250
RST     28H             97                      250
RST     30H             97                      250
RST     38H             97                      250

SBC     A,(HL)          48                      112
SBC     A,(IX+d)        48                      112
SBC     A,(IY+d)        48                      112
SBC     A,r             48                      112
SBC     A,n             48                      112
SBC     A,HX            *DEFB 0DDH + SBC A,H    ---
SBC     A,LX            *DEFB 0DDH + SBC A,L    ---
SBC     A,HY            *DEFB 0FDH + SBC A,H    ---
SBC     A,LY            *DEFB 0FDH + SBC A,L    ---
SBC     HL,BC           64                      151
SBC     HL,DE           64                      151
SBC     HL,HL           64                      151
SBC     HL,SP           64                      151

SCF                     58                      138

SET     b,(HL)          83                      212
SET     b,(IX+d)        84                      213
SET     b,(IY+d)        84                      215
SET     b,r             83                      211

SLA     (HL)            77                      189
SLA     (IX+d)          77                      189
SLA     (IY+d)          77                      189
SLA     r               77                      189
SLS     (HL)            *DEFB 0CBH,036H         ---
SLS     (IX+d)          *DEFB 0FDH,0CBH,dd,036H ---
SLS     (IY+d)          *DEFB 0FDH,0CBH,dd,036H ---
SLS     A               *DEFB 0CBH,037H         ---
SLS     B               *DEFB 0CBH,030H         ---
SLS     C               *DEFB 0CBH,031H         ---
SLS     D               *DEFB 0CBH,032H         ---
SLS     E               *DEFB 0CBH,033H         ---
SLS     H               *DEFB 0CBH,034H         ---
SLS     L               *DEFB 0CBH,035H         ---

SRA     (HL)            77                      192
SRA     (IX+d)          77                      192
SRA     (IY+d)          77                      192
SRA     r               77                      192
SRL     (HL)            78                      195
SRL     (IX+d)          78                      195
SRL     (IY+d)          78                      195
SRL     r               78                      195

SUB     (HL)            47                      110
SUB     (IX+d)          47                      110
SUB     (IY+d)          47                      110
SUB     r               47                      110
SUB     n               47                      110
SUB     HX              *DEFB 0DDH + SUB H      ---
SUB     LX              *DEFB 0DDH + SUB L      ---
SUB     HY              *DEFB 0FDH + SUB H      ---
SUB     LY              *DEFB 0FDH + SUB L      ---

XOR     (HL)            51                      118
XOR     (IX+d)          51                      118
XOR     (IY+d)          51                      118
XOR     r               51                      118
XOR     n               51                      118
XOR     HX              *DEFB 0DDH + XOR H      ---
XOR     LX              *DEFB 0DDH + XOR L      ---
XOR     HY              *DEFB 0FDH + XOR H      ---
XOR     LY              *DEFB 0FDH + XOR L      ---


--------------------------------------------------------
                        Appendix III                    
               Further Explanation of Terminal          
               and Fatal Errors, and Warnings           
--------------------------------------------------------

        Pages 125 and 126 of the Edtasm manual provide explanations for error messages displayed during entry, editing, and assembly.  The command errors are adequately described, but the terminal errors and warnings and unclear.


Terminal Error:      
Symbol Table Overflow
---------------------

When Edtasm assembles a source listing, it creates a table of each label, together with the address or data it specifies.  This table consists of all equates as well as labels within the source listing.  If there is not enough room in memory for the source code and the symbol table together, this message is displayed; it is the equivalent of Basic's ?OM ERROR.  By removing selected remarks or labels, the souce code may be successfully assembled.


Fatal Error:
Bad Label   
------------

Any label which starts with a non-alphabetic character, which is longer than 6 characters, or contains non-alphanumeric characters (such as & ! $ * % # etc.) will be rejected.  Also, labels which duplicate opcodes may not always be used (such as ADC, SLA, POP, etc.), and are not recommended because they cause confusion when reading and updating the source code.


Fatal Error:    
Expression Error
----------------

This error indicates that an error was made at some point in the operand.  For example, LD A,(H) would be rejected since the H register alone cannot specify a memory address.  An Expression Error most commonly arises when users familiar with 8080 language attempt to use those mnemonics with Edtasm, or when hexadecimal numbers are not specified.  Thus, LD (#$0400),A would be rejected since Zilog requires that hex information be written LD (0400H),A.  Similarly, LD HL,3C00 would be rejected since the hexadecimal indicator has not been appended; the correct form is LD HL,3C00H.  And finally, LD BC,FFFFH would be rejected because all addresses must begin with a number; this is correctly written LD BC,0FFFFH.


Fatal Error:           
Illegal Addressing Mode
-----------------------

There are many desirable Z80 instructions that, alas, do not exist.  For example LD B,(HL) is legal, whereas the equally useful LD B,(DE) or LD B,(BC) are not.  JP (HL) and JP (IX) are legal, but JP (BC) is not.  And so forth.  Also, note that there are many new opcodes listed in the following index; these will not be accepted, generating either this message or the Illegal Opcode message.


Fatal Error:  
Illegal Opcode
--------------

Again, 8080 programmers fall victim to this one.  STA #4350 would cause this error message.  The proper form is LD (4350),A.  Likewise, spaces accidentally left out during source code entry will create illegal opcodes (as in ADDA,43). A common error as users get more experienced with Edtasm is to substitute illegal opcodes suggested by actual ones (RRA might suggest RRB -- which does not exist and will generate an Illegal Opcode message -- or RRC -- which is an opcode of its own and will generate a Missing Information message; see below).


Fatal Error:       
Missing Information
-------------------

Most commonly, information in the operand has not been completed.  For example, just the opcode POP would produce this error message, as would LD A, or XOR.


Warning:           
Branch Out of Range
-------------------

The limit of all relative branches is -128 to +127 bytes from the beginning of the instruction.  As programs grow, formerly valid branches get pulled out of range.  When the Branch Out of Range message is presented, the assembly continues, but the instruction is assembled as a branch to itself, i.e., an endless loop to itself.  This error can be corrected by changing the relative branch (JR) to an absolute jump (JP).  A serious Edtasm bug exists with respect to the relative branch.  When a relative branch of exactly +128 bytes is specified, the code is assembled without the warning message -- but the assembled code produces a branch of -128 bytes.  Programs which do not function should be examined for this flaw caused by Edtasm.


Warning:      
Field Overflow
--------------

There are specific limits to the ranges of any instruction; see the index below for the ranges allowed.  When these ranges are exceeded, Field Overflow occurs.  Assembly continues, but the largest allowable value is assembled in the code.  This error can be corrected by adhering to the limit ranges.  In Edtasm Version 1.1, invalid Field Overflow occurs when negative offsets are applied to an index register (IX or IY).  For example, LD H,(IX-20) would produce a Field Overflow message, although it would assemble correctly.  However, LD H,(IX-130) would produce the error message and in fact would be an error since the allowable range is -128 to +127.


Warning:               
Multiply Defined Symbol
-----------------------

When a label (such as LOOP4) is assigned more than once in a program, this message is presented.  The first use of the label takes precedence over all others, but assembly continues.  To redefine a label, the assembler directive DEFL must be used at all occurrences; see the use of DEFL in the manual.


Warning:           
Multiple Definition
-------------------

This message often comes paired with the one above, and it indicates that a label is being redefined with EQU or DEFL.  Labels defined with EQU or as part of assembly code lines may only be used once, and may not be redefined using DEFL.  Only labels originally defined with DEFL may be redefined, and only with another use of DEFL.  See the use of EQU and DEFL in the manual.


Warning:        
No End Statement
----------------

The END statement is required for assembly.  Interestingly, if a program is assembled without an END statement, and object code is dumped to tape, the tape will continue to run and Edtasm will wait for the Break key to be pressed.  By paying careful attention to the end of the assembly, together with waiting through the leader, sync byte and program name (the first tone and burst of data) of a second assembly, programs too long for memory may be separately assembled and linked together on one tape.  This is not a convenient method, but it does work.  The END statement must then appear on the very last program to be linked.


Warning:        
Undefined Symbol
----------------

This message indicates that a symbol or label has not been defined, but is being used as an operand.  For example, if you have deleted the subroutine DELAY from your source code, but left a CALL DELAY in place somewhere, the Undefined Symbol message will be displayed.  All undefined symbols are set to zero during assembly.



--------------------------------------------------------
                      Appendix IV                       
                   Significant Errata                   
            to Radio Shack Editor/Assembler             
    (and to Zilog Assembly Language Programming Manual, 
            03-0002-01, Rev. B, April 1980)             
--------------------------------------------------------

Page 6:                                                 
        The program as shown will run destructively, i.e.,
        re-entry to Basic will be impossible because one
        byte too many is placed in the screen count.  To
        have this program run correctly, change line 00140
        to read:        LD      BC,3FFH                 
        and change the return-to-Basic point from complete
        system re-boot to Basic "warm start"; line 00250
        should read:    RET                             
        or              JP      06CCH                   


Page 7:                                                 
        The line numbers have been jumbled.  Line 00140 is
        actually 00130, and line 0040 is  00140.  This was
        probably typed by hand, not actual computer output.


Page 26 (page 58 in Zilog manual):                      
correct:      "...contains 65H and address 2131M ..."   
to read:      "...contains 65H and address 2131H ..."   


Page 32 (page 72 in Zilog manual):                      
note:   Although the condition code bits are not formally
        affected by a this instruction, POP AF will place
        the previously PUSHed value in the condition code
        register F (flags).                             


Page 64 (page 154 in Zilog manual):                     
correct:      "...Index Register IX are 333H and ..."   
to read:      "...Index Register IX are 3333H and ..."  


Page 75 (Zilog manual is correct):                      
correct:      RR (IY+d)  ( 0 0 0 1 1 1 1 0 ) 1E         
to read:      RR (IY+d)  ( 1 1 1 1 1 1 0 1 ) FD         

Page 103 (Zilog manual is correct):                     
correct:      "... execution of OUT 01H,A the byte ..." 
to read:      "... execution of OUT (01H),A the byte..."

Page 106 (page 271 in Zilog manual):                    
correct:      "... the register pair HL is incremented."
to read:      "... the register pair HL is decremented."

Page 114 (page 290 in Zilog manual):                    
correct:      0062    44     69       LD B,H,NN         
to read:      0062    44     69       LD B,H            


Page 117 (page 294 in Zilog manual):                    
add:          043E(a) ED4F   583(a)   LD R,A            
add:          0459(a) ED5F   594(a)   LD A,R            


Page 121 (page 286 in Zilog manual):                    
add:          022F(a) ED5F   279(a)   LD A,R            


Page 122 (page 286 in Zilog manual):                    
add:          02B5(a) ED4F            LD R,A            


Page 128, under "Keyboard Scan":                        
correct:      JR        A,AGN   ;BRANCH IF NO BYTE      
to read:      JR        Z,AGN   ;BRANCH IF NO BYTE      


Page 130, opposite 15360 in the memory map:             
correct:      3000                                      
to read:      3C00                                      


----------------------------------------------------------------

filename:TEMP13 <used to be in lesson 12>

EDTASM's command to assemble your mnemonics into machine language is "A".  The "A" command has a number of options called "switches".  If you enter simply the letter "A", the assembler will display a scrolling assembled listing, will provide a table of all labels you've used in the source code, note any errors you've generated, and -- assuming you have a tape recorder connected and ready -- will prepare a cassette containing the final binary object code.  The object code tape will be called "NONAME", and will load under BASIC's CLOADM command.

There are many other options that this one.  The format of the "A" command is A, space, filename, switch.  For example, to assemble and save the resulting machine-language program to tape under the name "DISPLAY", you would type A DISPLAY <ENTER>.

The switches are two-letter command options separated by slashes.  These are:

/WE             Wait for errors.  The display stops if you
                have made an error in an opcode, an operand,
                a range, a typo, etc.  The assembler will
                display a descriptive error message.
/NO             No object code tape is created.  I use this
                switch until I have eliminated all errors
                picked up by the assembler.
/NL             No listing is displayed.  Especially during
                correction of minor errors, or when you only
                want to see a list of labels, you can turn
                off the long listing.
/NS             No symbol table is displayed.  The symbol
                table is the proper name for a list of all
                the labels used in the program, together with
                the addresses at which they appear.
/LP             Line printer command.  Everything that is
                displayed on screen is also sent to the
                Color Computer's serial printer.
/IM             In-memory assembly.  This is an excellent
                debugging tool.  The program is not only
                assembled into binary code, it is also placed
                directly in memory, ready to run.
/AO             Absolute origin.  If you do an in-memory
                assembly, you can let the machine assemble
                the program at its predetermined location,
                or at the memory location you specified in
                your ORG statement.  Absolute origin uses
                your ORG.
/MO             Manual origin.  This permits you to move the
                source code, tables, and so forth, that
                EDTASM needs to work with, so that your own
                program doesn't conflict with it.
/SS             This is the short screen option.  Finding
                your way through an assembling program with
                the Color Computer's 32-character screen
                can be messy.  The short screen places the
                assembled hex address, opcodes and operand
                on a line by themselves, with the mnemonics
                out of the way on the next line.

For details on all these commands, of course, read pages 13 through 16 of your EDTASM+ manual.  For the moment, I want you to try the In-Memory assembly option, at your own origin.
